What

Follow-up to #36 (merged before these landed). Two commits: my pre-merge self-review simplification pass, plus fixes for the findings of a full review of #36.

Correctness

• select_best can no longer restore a class-collapsed pass. Best-iteration snapshots now rank on report_score — accuracy penalized below any healthy score when a class sits under the recall floor — the same rule the gate uses. Previously a degenerate all-neutral pass (e.g. 0.65 with up-recall 0.0) that the collapse floor refused to ship could still be snapshotted as "best" and restored into the finals.
• Finalize can't flip the verdict anymore. The explanations-in-hand invocation routes straight to the finalize node instead of re-running decide on the (possibly restored) report — which also removes the iteration-bump/history-dedup special cases and a wasted LLM rationale call.
• Collapse-forced first retune takes the schedule. When the floor blocks an above-target pass, Sabina's proposal says proceed and carries no suggested_params; the gate previously "accepted" {} and re-ran Nadi's defaults, wasting an iteration and poisoning tried_params.
• Perturb candidates carry both knobs. A single-key dict (best = iteration 1 defaults) made _same() falsely skip untried schedule entries. boost_factor is also clamped (_BOOST_MAX) — threshold was clamped, boost grew without bound.
• clean_outputs() runs after Aurora succeeds, not at run start — a run that dies on its inputs (typo'd --data-dir) no longer wipes the previous run's deliverables first.

Cleanup

• One shared load_dotenv in agents/env.py (was copy-pasted into finetune_finbert.py — @nadi, touches your file again, same footprint as before).
• sample_size passed into build_pipeline explicitly; the agents.manager._defaults private reach-in is gone.
• HISTORY_DIR named once; _next_params index mapping simplified; mock formatting churn reverted; pipeline test fakes deduped.
• docs/retune_loop.md no longer contradicts docs/finetune_runs.md on the fine-tune-vs-baseline verdict.

Surfaced, not fixed (Sabina's lane)

class_accuracy is 0.0 for a label with zero test rows — indistinguishable from a collapse, so a window missing a label can never clear the target (documented in retune_loop.md). Needs per-class support in evaluation_report.json.

Branches merged into this one

Since this PR was opened, two more branches landed on top of feature/manager-adapt:

• Evaluator: score retunes on a val split; test set touched once #37 fix/eval-val-split — retune loop now evaluates on a val split instead of the test split (test is scored exactly once, at the end). Touches nadi_classifier.py, sabina_evaluator.py, jack_manager.py, finetune_finbert.py.
• Share handoff file rules #39 feature/contracts-module — new agents/contracts.py centralizes the handoff-file column lists/validation that were previously duplicated across agents. Also includes my own --dataset-end CLI fix (restores a flag that had been accidentally reverted, so full-pipeline runs can exclude the COVID window from the test split again).

For my teammates (Freddi, Aurora, Sabina, Nadi)

The contracts centralization (#39) touches your agent files directly, not just mine. Please check the diff on your file specifically for behavior changes, don't assume it's purely mechanical:

• Freddi — agents/freddi_explanation.py
• Aurora — agents/aurora_processing.py
• Sabina — agents/sabina_evaluator.py
• Nadi — agents/nadi_classifier.py

I also modified the notebooks below as part of that same change — I updated them to match, but I have not fully re-verified them end to end, so please check your own before trusting it:

• docs/explanation_agent_walkthrough.ipynb (Freddi)
• docs/nadi_classifier_guide.ipynb (Nadi)
• docs/sabina_evaluator_guide.ipynb (Sabina)

Verification

• 60 tests pass (uv run pytest tests/), including new regression tests: collapsed pass never outranks healthy, collapse-forced retune params, full-key perturbs, boost clamp, failed-start keeps previous outputs.